@brett_lamy/docstream 1.3.0 → 1.4.0

package/README.md

@@ -632,21 +632,41 @@ import { ReactDemo } from "@brett_lamy/docstream/playground"
 
 ## Bundler Notes
 
-This release ships TypeScript and TSX source through ESM exports:
+Since 1.4 the package ships compiled ES modules (ES2022, `react-jsx`) with type
+declarations and declaration maps — one file per source module in `dist/`,
+dependencies left as imports, lazy features (Mermaid, KaTeX, rrweb, the
+playground's almost-node) still behind dynamic `import()`:
 
 ```json
 {
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./dist/styles.css"
   }
 }
 ```
 
-It is validated with Vite and modern TypeScript `moduleResolution: "Bundler"`. Plain Node.js, CommonJS, or tooling that does not transpile TypeScript in dependencies may need a future precompiled JS build.
+No bundler configuration is needed: Vite pre-bundles docstream like any other
+dependency (no `optimizeDeps` entries), Next.js and webpack consume it as plain
+ESM, and your type-check reads `.d.ts` files instead of docstream's sources. The
+`@brett_lamy/docstream/vite` entry is a Node-only Vite plugin; import it from
+`vite.config.ts`, never from browser code.
+
+The TypeScript sources are published too, behind a `source` export condition, for
+monorepos that want to compile docstream from source (e.g. Vite
+`resolve.conditions: ["source", ...]` or TypeScript `customConditions`).
+
+## Migrating to 1.4
+
+No API changes. Exports now resolve to `dist/*.js` + `dist/*.d.ts` instead of
+`src/*.ts(x)`; drop any `optimizeDeps.include` / `exclude` or
+`transpilePackages` entries you added for docstream, and any `lib` / `types`
+settings you added only so your type-check could compile docstream's sources.
 
 ## Migrating to 1.3
 

package/dist/assets.d.ts

@@ -0,0 +1,3 @@
+export declare function setAssetBase(repo: string | null, branch: string | null, filePath: string | null): void;
+export declare function resolveAsset(src: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAMA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,QAO/F;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD"}

package/dist/assets.js

@@ -0,0 +1,20 @@
+// Resolves repo-relative image paths (e.g. "readme-assets/logo.svg") against
+// the raw.githubusercontent.com URL of the file being edited. The AST keeps
+// the original relative src; only rendering resolves it.
+let assetBase = null;
+export function setAssetBase(repo, branch, filePath) {
+    if (!repo || !branch || !filePath) {
+        assetBase = null;
+        return;
+    }
+    const dir = filePath.includes("/") ? filePath.slice(0, filePath.lastIndexOf("/") + 1) : "";
+    assetBase = `https://raw.githubusercontent.com/${repo}/${branch}/${dir}`;
+}
+export function resolveAsset(src) {
+    if (!src || /^(https?:|data:|blob:)/i.test(src))
+        return src;
+    if (!assetBase)
+        return src;
+    return assetBase + src.replace(/^\.\//, "");
+}
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,yDAAyD;AAEzD,IAAI,SAAS,GAAkB,IAAI,CAAA;AAEnC,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,MAAqB,EAAE,QAAuB;IAC9F,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,SAAS,GAAG,IAAI,CAAA;QAChB,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1F,SAAS,GAAG,qCAAqC,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAA;AAC1E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,GAAG,IAAI,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAC3D,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAA;IAC1B,OAAO,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AAC7C,CAAC"}

package/dist/demo/DemoViewer.d.ts

@@ -0,0 +1,64 @@
+import { type CSSProperties } from "react";
+import type { DemoLayout, DemoNode, DemoViewport } from "../gitbook/ast.js";
+import type { DemoFile, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types.js";
+export interface DemoViewerProps {
+    /** `<page>/<example>` id handed to the resolver. */
+    src: string;
+    /** Defaults to the nearest `demoResolver` provided to a renderer. */
+    resolver?: DemoResolver;
+    title?: string;
+    description?: string;
+    /** Preview height (px number, digits, or any CSS length). */
+    height?: number | string;
+    layout?: DemoLayout;
+    variants?: DemoVariant[];
+    /** Initial viewport of the multi-file preview. */
+    viewport?: DemoViewport;
+    /**
+     * Files carried inline by the block (entry first unless `entry` says otherwise). Used when
+     * no resolver knows `src`, or the resolver fails for it.
+     */
+    files?: DemoFile[];
+    /** Entry among `files`. Defaults to the first file. */
+    entry?: string;
+    /** The block is still streaming in: show its code, but don't run it yet. */
+    streaming?: boolean;
+    /** Runs inline files in the Preview. Defaults to the runtime in context (`demoRuntime`). */
+    runtime?: InlineDemoRuntime;
+    /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
+    dependencies?: Record<string, string>;
+    /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
+    className?: string;
+    /** Status shown in the header (`meta.status`). */
+    status?: string;
+    /** Full-bleed canvas without the padded surface (`meta.bleed`). */
+    bleed?: boolean;
+    /** Extra class on the preview canvas (`meta.className`). */
+    canvasClassName?: string;
+    /** Canvas inline style: an object like `meta.surface`, or CSS declarations as in the tag's `surface`. */
+    surface?: Record<string, string | number> | string;
+    /** Width of the variant switch (`meta.variantsWidth`). */
+    variantsWidth?: number | string;
+}
+/**
+ * Resolve demos ahead of rendering (meta, files and component), so the first render — including
+ * server rendering and static export — shows them resolved instead of loading. Failures are
+ * remembered too, so inline-file fallbacks apply immediately.
+ */
+export declare function preloadDemos(resolver: DemoResolver, srcs: string[]): Promise<void>;
+export declare const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead.";
+export declare function DemoViewer(props: DemoViewerProps): import("react").JSX.Element;
+/** Renders a parsed `{% demo %}` block with the resolver and runtime from context. */
+export declare function DemoBlock({ node }: {
+    node: DemoNode;
+}): import("react").JSX.Element;
+export interface DemoFullscreenProps {
+    src: string;
+    resolver?: DemoResolver;
+    variant?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** One demo filling the viewport, for a `?demo=<src>` deep link the host routes. */
+export declare function DemoFullscreen({ src, resolver: override, variant, className, style }: DemoFullscreenProps): import("react").JSX.Element;
+//# sourceMappingURL=DemoViewer.d.ts.map

package/dist/demo/DemoViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DemoViewer.d.ts","sourceRoot":"","sources":["../../src/demo/DemoViewer.tsx"],"names":[],"mappings":"AAcA,OAAO,EAQL,KAAK,aAAa,EAKnB,MAAM,OAAO,CAAA;AAId,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAUxE,OAAO,KAAK,EAAiB,QAAQ,EAAY,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9G,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;IAClB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAA;IAMlB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yGAAyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAA;IAClD,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAChC;AAaD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AA2HD,eAAO,MAAM,eAAe,0EAA0E,CAAA;AA4VtG,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA8KhD;AAyGD,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,+BAoBrD;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,mBAAmB,+BAYzG"}

package/dist/demo/DemoViewer.js

@@ -0,0 +1,426 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/* The demo viewer for `{% demo src="<page>/<example>" %}`.
+
+   Where the files come from:
+   - a host `DemoResolver` that knows `src`: the component renders in-page; the Code view shows
+     the resolver's files (they win over any inline copy);
+   - otherwise the block's inline files (`{% demo %}` + fences + `{% enddemo %}`): the Preview
+     runs them through the `InlineDemoRuntime` in context (almost-node in the playground entry),
+     or, without one, the viewer opens on the Code view with a short note — never an empty box.
+
+   Multi-file demos get the gallery viewer: a header (title, description, Preview | Code, variants,
+   viewport widths, copy, fullscreen), a resizable preview frame on a dotted stage, and a Code view
+   with a file tree and highlighted source. Single-file demos keep the ReactDemo card: the preview,
+   then a collapsible, line-numbered code panel. Either way the component renders in-page (lazy
+   `load()`, mounted once the card nears the viewport) and the code shown is the real file. */
+import { Component, createElement, useEffect, useId, useMemo, useRef, useState, } from "react";
+import { motion, useReducedMotion } from "framer-motion";
+import { ExternalLink, FileCode2, Folder, Maximize2, Monitor, Smartphone, Tablet, X } from "lucide-react";
+import { parseInline } from "../gitbook/inline.js";
+import { CollapsibleCode } from "../docs/CollapsibleCode.js";
+import { HighlightedCode } from "../docs/HighlightedCode.js";
+import { CopyButton } from "../docs/copy.js";
+import { PillTabs, Segmented, rovingKeyDown } from "../docs/controls.js";
+import { useDemoResolver, useDemoRuntime } from "./context.js";
+import { languageForPath } from "./glob.js";
+import { inlineDemoMarkdown } from "./markdown.js";
+import { cssToSurface, surfaceStyle, surfaceToCss } from "./surface.js";
+const settled = new WeakMap();
+function cacheFor(resolver) {
+    let cache = settled.get(resolver);
+    if (!cache)
+        settled.set(resolver, (cache = new Map()));
+    return cache;
+}
+/**
+ * Resolve demos ahead of rendering (meta, files and component), so the first render — including
+ * server rendering and static export — shows them resolved instead of loading. Failures are
+ * remembered too, so inline-file fallbacks apply immediately.
+ */
+export async function preloadDemos(resolver, srcs) {
+    const cache = cacheFor(resolver);
+    const settle = async (key, run) => {
+        try {
+            cache.set(key, { status: "ready", value: await run() });
+        }
+        catch (cause) {
+            cache.set(key, { status: "error", error: cause instanceof Error ? cause : new Error(String(cause)) });
+        }
+    };
+    await Promise.all(srcs.flatMap((src) => [
+        settle(`meta:${src}`, () => resolver.meta(src)),
+        settle(`files:${src}`, () => resolver.files(src)),
+        settle(`load:${src}`, () => resolver.load(src)),
+    ]));
+}
+/** Resolves `run()` once `active`, remembering settled values so remounts don't flash. */
+function useResolved(resolver, key, active, run) {
+    const cached = resolver ? cacheFor(resolver).get(key) : undefined;
+    const [state, setState] = useState(cached ?? { status: "loading" });
+    useEffect(() => {
+        if (!resolver)
+            return;
+        const hit = cacheFor(resolver).get(key);
+        if (hit && hit.status !== "loading") {
+            setState(hit);
+            return;
+        }
+        if (!active) {
+            setState({ status: "loading" });
+            return;
+        }
+        let live = true;
+        run().then((value) => {
+            const next = { status: "ready", value };
+            cacheFor(resolver).set(key, next);
+            if (live)
+                setState(next);
+        }, (cause) => {
+            const error = cause instanceof Error ? cause : new Error(String(cause));
+            if (live)
+                setState({ status: "error", error });
+        });
+        return () => {
+            live = false;
+        };
+        // `run` closes over resolver + key only.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [resolver, key, active]);
+    return state;
+}
+const useMeta = (resolver, src) => useResolved(resolver, `meta:${src}`, true, () => resolver.meta(src));
+const useFiles = (resolver, src, active) => useResolved(resolver, `files:${src}`, active, () => resolver.files(src));
+const useComponent = (resolver, src, active) => useResolved(resolver, `load:${src}`, active, () => resolver.load(src));
+/** True once the element has come within `margin` of the viewport (stays true). */
+function useNearViewport(margin = "400px 0px") {
+    const ref = useRef(null);
+    const [near, setNear] = useState(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || near)
+            return;
+        if (typeof IntersectionObserver === "undefined") {
+            setNear(true);
+            return;
+        }
+        const observer = new IntersectionObserver(([entry]) => {
+            if (entry?.isIntersecting)
+                setNear(true);
+        }, { rootMargin: margin });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [near, margin]);
+    return [ref, near];
+}
+/* ---------- pieces ---------- */
+class DemoErrorBoundary extends Component {
+    state = { error: null };
+    static getDerivedStateFromError(error) {
+        return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+    componentDidUpdate(prev) {
+        if (prev.src !== this.props.src && this.state.error)
+            this.setState({ error: null });
+    }
+    render() {
+        return this.state.error ? _jsx(DemoError, { message: `${this.props.src} failed to render: ${this.state.error.message}` }) : this.props.children;
+    }
+}
+function DemoError({ message }) {
+    return _jsx("pre", { className: "docs-demo-error", role: "alert", children: message });
+}
+function Spinner({ label = "Loading demo" }) {
+    return (_jsx("div", { className: "docs-demo-loading", role: "status", "aria-label": label, children: _jsx("span", { className: "docs-demo-spinner", "aria-hidden": "true" }) }));
+}
+/** Descriptions allow inline Markdown (`code`, **bold**, _em_, links). */
+function InlineMarkdown({ text }) {
+    const nodes = useMemo(() => parseInline(text), [text]);
+    return (_jsx(_Fragment, { children: nodes.map((n, i) => {
+            if (n.type !== "text")
+                return null;
+            let el = n.text;
+            if (n.code)
+                el = _jsx("code", { children: el });
+            if (n.bold)
+                el = _jsx("strong", { children: el });
+            if (n.italic)
+                el = _jsx("em", { children: el });
+            if (n.link)
+                el = _jsx("a", { href: n.link, children: el });
+            return _jsx("span", { children: el }, i);
+        }) }));
+}
+function cssLength(value, fallback) {
+    if (value === undefined || value === "")
+        return fallback;
+    if (typeof value === "number")
+        return `${value}px`;
+    return /^\d+(?:\.\d+)?$/.test(value.trim()) ? `${value.trim()}px` : value;
+}
+export const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead.";
+function DemoCanvas({ src, preview, variant, bleed, look }) {
+    if (preview.kind === "unavailable" || preview.kind === "streaming") {
+        return (_jsx("div", { className: "docs-demo-note", role: "note", "data-variant": variant, children: preview.kind === "streaming" ? "The demo is still arriving; its preview starts once the block is complete." : NO_RUNTIME_NOTE }));
+    }
+    if (preview.kind === "runtime") {
+        return (_jsx("div", { className: ["docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime", look?.className ?? ""].filter(Boolean).join(" "), style: surfaceStyle(look?.surface), "data-variant": variant, children: _jsx(DemoErrorBoundary, { src: src || "demo", children: preview.render(variant) }) }));
+    }
+    const { component } = preview;
+    return (_jsx("div", { className: ["docs-demo-canvas", bleed ? "docs-demo-canvas-bleed" : "", look?.className ?? ""].filter(Boolean).join(" "), style: surfaceStyle(look?.surface), "data-variant": variant, children: component.status === "ready" ? (_jsx(DemoErrorBoundary, { src: src, children: createElement(component.value, variant === undefined ? {} : { variant }) })) : component.status === "error" ? (_jsx(DemoError, { message: `${src} failed to load: ${component.error.message}` })) : (_jsx(Spinner, {})) }));
+}
+const VIEWPORTS = [
+    { id: "desktop", label: "Desktop", width: null, Icon: Monitor },
+    { id: "tablet", label: "Tablet", width: 768, Icon: Tablet },
+    { id: "phone", label: "Phone", width: 390, Icon: Smartphone },
+];
+const MIN_WIDTH = 280;
+/** The resizable preview frame on its stage. `width === null` fills the stage. */
+function PreviewStage({ width, onResize, height, children }) {
+    const reduced = useReducedMotion();
+    const frame = useRef(null);
+    const [dragging, setDragging] = useState(false);
+    const [measured, setMeasured] = useState(null);
+    const [max, setMax] = useState(0);
+    useEffect(() => {
+        const el = frame.current;
+        if (!el || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => {
+            setMeasured(Math.round(el.getBoundingClientRect().width));
+            setMax(el.parentElement?.clientWidth ?? 0);
+        });
+        observer.observe(el);
+        if (el.parentElement)
+            observer.observe(el.parentElement);
+        return () => observer.disconnect();
+    }, []);
+    const clamp = (next) => {
+        const limit = frame.current?.parentElement?.clientWidth ?? next;
+        const value = Math.round(Math.min(limit, Math.max(MIN_WIDTH, next)));
+        return value >= limit - 4 ? null : value;
+    };
+    const startDrag = (event) => {
+        const el = frame.current;
+        if (!el || event.button !== 0)
+            return;
+        event.preventDefault();
+        const left = el.getBoundingClientRect().left;
+        setDragging(true);
+        const move = (ev) => onResize(clamp(ev.clientX - left));
+        const up = () => {
+            setDragging(false);
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", up);
+            window.removeEventListener("pointercancel", up);
+        };
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointerup", up);
+        window.addEventListener("pointercancel", up);
+    };
+    const onKeyDown = (event) => {
+        const current = width ?? measured ?? max;
+        const step = event.shiftKey ? 50 : 10;
+        let next;
+        if (event.key === "ArrowLeft")
+            next = clamp(current - step);
+        else if (event.key === "ArrowRight")
+            next = clamp(current + step);
+        else if (event.key === "Home")
+            next = clamp(MIN_WIDTH);
+        else if (event.key === "End")
+            next = null;
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        onResize(next);
+    };
+    return (_jsxs("div", { className: "docs-demo-stage", style: { height }, "data-dragging": dragging || undefined, children: [_jsx(motion.div, { ref: frame, className: "docs-demo-frame", "data-sized": width !== null || undefined, initial: false, animate: { width: width ?? "100%" }, transition: dragging || reduced ? { duration: 0 } : { type: "spring", bounce: 0.12, duration: 0.5 }, children: children }), _jsx("div", { className: "docs-demo-handle", role: "separator", tabIndex: 0, "aria-orientation": "vertical", "aria-label": "Resize preview", "aria-valuemin": MIN_WIDTH, "aria-valuemax": max || undefined, "aria-valuenow": measured ?? undefined, "aria-valuetext": measured ? `${measured} pixels wide` : undefined, "data-dragging": dragging || undefined, onPointerDown: startDrag, onKeyDown: onKeyDown, onDoubleClick: () => onResize(null) }), _jsx("span", { className: "docs-demo-readout", "aria-hidden": "true", children: measured ? `${measured}px` : "" })] }));
+}
+/** Files as a tree: the entry and root files first, then each folder with its files indented. */
+function fileTree(files) {
+    const rows = [];
+    const seen = new Set();
+    for (const file of files) {
+        const parts = file.path.split("/");
+        for (let d = 0; d < parts.length - 1; d++) {
+            const dir = parts.slice(0, d + 1).join("/");
+            if (!seen.has(dir)) {
+                seen.add(dir);
+                rows.push({ kind: "dir", name: parts[d], depth: d, path: dir });
+            }
+        }
+        rows.push({ kind: "file", name: parts[parts.length - 1], depth: parts.length - 1, path: file.path });
+    }
+    return rows;
+}
+function CodeView({ src, files, height, id }) {
+    const [active, setActive] = useState(files[0]?.path ?? "");
+    useEffect(() => {
+        if (!files.some((f) => f.path === active))
+            setActive(files[0]?.path ?? "");
+    }, [files, active]);
+    const file = files.find((f) => f.path === active) ?? files[0];
+    const rows = useMemo(() => fileTree(files), [files]);
+    const paths = files.map((f) => f.path);
+    const tabId = (path) => `${id}-file-${paths.indexOf(path)}`;
+    const panelId = `${id}-source`;
+    return (_jsxs("div", { className: "docs-demo-code", style: { height }, children: [_jsxs("div", { className: "docs-demo-files", role: "tablist", "aria-orientation": "vertical", "aria-label": "Files", onKeyDown: (event) => rovingKeyDown(event, paths, active, setActive, "vertical"), children: [_jsx("div", { className: "docs-demo-files-h", "aria-hidden": "true", children: "Files" }), rows.map((row) => row.kind === "dir" ? (_jsxs("div", { className: "docs-demo-dir", style: { "--depth": row.depth }, "aria-hidden": "true", children: [_jsx(Folder, { width: 13, height: 13, "aria-hidden": "true" }), row.name] }, `d:${row.path}`)) : (_jsxs("button", { id: tabId(row.path), type: "button", role: "tab", "data-roving": "", "aria-selected": row.path === active, "aria-controls": panelId, tabIndex: row.path === active ? 0 : -1, title: row.path, className: "docs-demo-file", style: { "--depth": row.depth }, onClick: () => setActive(row.path), children: [_jsx(FileCode2, { width: 13, height: 13, "aria-hidden": "true" }), _jsx("span", { children: row.name })] }, row.path)))] }), _jsxs("div", { className: "docs-demo-source", role: "tabpanel", id: panelId, "aria-labelledby": file ? tabId(file.path) : undefined, children: [_jsxs("div", { className: "docs-demo-source-h", children: [_jsx("span", { className: "docs-demo-source-path", children: src && file ? `${src}/${file.path}` : file?.path }), file ? _jsx(CopyButton, { text: file.content, label: `Copy ${file.path}` }) : null] }), _jsx("div", { className: "docs-demo-source-body", tabIndex: 0, "aria-label": file ? `${file.path} source` : undefined, children: file ? (_jsx("pre", { className: "docs-code-numbered", children: _jsx(HighlightedCode, { code: file.content.replace(/\n+$/, ""), language: file.language ?? languageForPath(file.path) ?? null, lineNumbers: true }) })) : (_jsx(Spinner, { label: "Loading files" })) })] })] }));
+}
+function FullscreenButton({ onOpen, title }) {
+    return (_jsx("button", { type: "button", className: "docs-demo-icon-btn", onClick: onOpen, "aria-label": `Open ${title} fullscreen`, title: "Fullscreen", children: _jsx(Maximize2, { width: 15, height: 15, "aria-hidden": "true" }) }));
+}
+function NewTabLink({ href, title }) {
+    if (!href)
+        return null;
+    return (_jsx("a", { className: "docs-demo-icon-btn", href: href, target: "_blank", rel: "noreferrer", "aria-label": `Open ${title} in a new tab`, title: "Open in new tab", children: _jsx(ExternalLink, { width: 15, height: 15, "aria-hidden": "true" }) }));
+}
+function VariantSwitch({ variants, value, onChange, title, width }) {
+    if (!variants?.length || value === undefined)
+        return null;
+    return (_jsx(Segmented, { options: variants, value: value, onChange: onChange, label: `${title} variant`, className: width === undefined ? "docs-demo-variants" : "docs-demo-variants docs-demo-variants-sized", style: width === undefined ? undefined : { width: cssLength(width, "auto") } }));
+}
+function StatusBadge({ status }) {
+    return status ? _jsx("span", { className: "docs-demo-status", children: status }) : null;
+}
+/** A full-viewport overlay (native modal dialog: top layer, focus trap, Esc to close). */
+function FullscreenDialog({ open, onClose, title, src, variants, variant, onVariant, preview, bleed, look, variantsWidth, href }) {
+    const ref = useRef(null);
+    const titleId = useId();
+    useEffect(() => {
+        const dialog = ref.current;
+        if (!dialog)
+            return;
+        if (open && !dialog.open) {
+            if (typeof dialog.showModal === "function")
+                dialog.showModal();
+            else
+                dialog.setAttribute("open", "");
+        }
+        else if (!open && dialog.open) {
+            dialog.close();
+        }
+    }, [open]);
+    return (_jsx("dialog", { ref: ref, className: "docs-demo-dialog", "aria-labelledby": titleId, onClose: onClose, onCancel: onClose, children: open ? (_jsxs("div", { className: "docs-demo-dialog-inner", children: [_jsxs("div", { className: "docs-demo-dialog-bar", children: [_jsx("span", { id: titleId, className: "docs-demo-title", children: title }), _jsx("span", { className: "docs-demo-dialog-src", children: src }), _jsx("span", { className: "docs-demo-spacer" }), _jsx(VariantSwitch, { variants: variants, value: variant, onChange: onVariant, title: title, width: variantsWidth }), _jsx(NewTabLink, { href: href, title: title }), _jsx("button", { type: "button", className: "docs-demo-icon-btn", onClick: onClose, "aria-label": "Close fullscreen", title: "Close (Esc)", autoFocus: true, children: _jsx(X, { width: 16, height: 16, "aria-hidden": "true" }) })] }), _jsx("div", { className: "docs-demo-dialog-stage", children: _jsx(DemoCanvas, { src: src, preview: preview, variant: variant, bleed: bleed, look: look }) })] })) : null }));
+}
+/** Inline files, entry first. */
+function orderInline(files, entry) {
+    if (!files?.length)
+        return undefined;
+    const index = entry ? files.findIndex((f) => f.path === entry) : -1;
+    return index > 0 ? [files[index], ...files.slice(0, index), ...files.slice(index + 1)] : files;
+}
+export function DemoViewer(props) {
+    const resolver = useDemoResolver(props.resolver);
+    const runtimeOptions = useDemoRuntime({ runtime: props.runtime, dependencies: props.dependencies });
+    const { src } = props;
+    const [ref, near] = useNearViewport();
+    const inlineFiles = useMemo(() => orderInline(props.files, props.entry), [props.files, props.entry]);
+    // A resolver is consulted unless the block brings its own files and the resolver
+    // says (via `list()`) that it does not know this src.
+    const tryResolver = !!resolver && !(inlineFiles && (!src || (resolver.list ? !resolver.list().includes(src) : false)));
+    const hookResolver = tryResolver ? resolver : undefined;
+    const meta = useMeta(hookResolver, src);
+    const resolvedFiles = useFiles(hookResolver, src, near);
+    const component = useComponent(hookResolver, src, near);
+    const resolverFailed = meta.status === "error" || resolvedFiles.status === "error" || component.status === "error";
+    const mode = tryResolver && !(inlineFiles && resolverFailed) ? "resolver" : inlineFiles ? "inline" : "none";
+    const metaValue = mode === "resolver" && meta.status === "ready" ? meta.value : undefined;
+    const files = mode === "inline" ? { status: "ready", value: inlineFiles } : resolvedFiles;
+    const title = props.title ?? metaValue?.title ?? (src.split("/").pop() || "Demo");
+    const description = props.description ?? metaValue?.description;
+    const variants = props.variants?.length ? props.variants : metaValue?.variants;
+    const [chosenVariant, setVariant] = useState(undefined);
+    const variant = variants?.length
+        ? (variants.some((v) => v.id === chosenVariant) ? chosenVariant : variants[0].id)
+        : undefined;
+    const layoutPref = props.layout ?? metaValue?.layout ?? "auto";
+    const fileList = files.status === "ready" ? files.value : null;
+    const layout = layoutPref !== "auto" ? layoutPref : fileList ? (fileList.length > 1 ? "multi" : "single") : null;
+    const heightValue = props.height ?? metaValue?.height;
+    // Look: the tag's attributes (props) first, then `meta.json`.
+    const bleed = props.bleed ?? metaValue?.bleed;
+    const propSurface = typeof props.surface === "string" ? cssToSurface(props.surface) : props.surface;
+    const look = {
+        className: props.canvasClassName ?? metaValue?.className,
+        surface: propSurface ?? metaValue?.surface,
+    };
+    const variantsWidth = props.variantsWidth ?? metaValue?.variantsWidth;
+    const status = props.status ?? metaValue?.status;
+    const [fullscreen, setFullscreen] = useState(false);
+    const href = mode === "resolver" ? resolver?.href?.(src, variant ? { variant } : undefined) : undefined;
+    const baseId = useId();
+    const { runtime, dependencies } = runtimeOptions;
+    const preview = useMemo(() => {
+        if (mode !== "inline")
+            return { kind: "component", component };
+        if (props.streaming)
+            return { kind: "streaming" };
+        if (!runtime || !inlineFiles)
+            return { kind: "unavailable" };
+        const entry = inlineFiles[0].path;
+        return { kind: "runtime", render: (v) => runtime({ src, title, files: inlineFiles, entry, variant: v, dependencies }) };
+    }, [mode, component, props.streaming, runtime, inlineFiles, src, title, dependencies]);
+    const runnable = preview.kind !== "unavailable";
+    if (mode === "none") {
+        return (_jsxs("div", { className: "docs-source-ref", "data-docstream-demo": "", "data-demo-src": src, children: [_jsx(FileCode2, { width: 16, height: 16, "aria-hidden": "true" }), _jsx("span", { children: title }), _jsxs("code", { children: ["demo:", src] })] }));
+    }
+    const node = {
+        type: "demo",
+        src,
+        ...(props.title ? { title: props.title } : {}),
+        ...(props.description ? { description: props.description } : {}),
+        ...(props.height !== undefined ? { height: String(props.height) } : {}),
+        ...(props.layout ? { layout: props.layout } : {}),
+        ...(props.variants?.length ? { variants: props.variants } : {}),
+        ...(props.viewport ? { viewport: props.viewport } : {}),
+        ...(props.status ? { status: props.status } : {}),
+        ...(props.bleed !== undefined ? { bleed: props.bleed } : {}),
+        ...(props.canvasClassName ? { className: props.canvasClassName } : {}),
+        ...(props.surface ? { surface: typeof props.surface === "string" ? props.surface : surfaceToCss(props.surface) } : {}),
+        ...(props.variantsWidth !== undefined && props.variantsWidth !== "" ? { variantsWidth: String(props.variantsWidth) } : {}),
+    };
+    const copyDemo = () => inlineDemoMarkdown(node, fileList ?? [], metaValue);
+    const dialog = (_jsx(FullscreenDialog, { open: fullscreen, onClose: () => setFullscreen(false), title: title, src: src, variants: variants, variant: variant, onVariant: setVariant, preview: preview, bleed: bleed, look: look, variantsWidth: variantsWidth, href: href }));
+    const wrapper = (kind) => ["docs-demo", `docs-demo-${kind}`, props.className].filter(Boolean).join(" ");
+    if (layout === "single") {
+        const file = fileList?.[0];
+        return (_jsxs("section", { ref: ref, className: wrapper("single"), "data-docstream-demo": "", "data-demo-src": src, "data-demo-mode": mode, "aria-labelledby": `${baseId}-title`, children: [_jsxs("div", { className: "docs-react-demo", children: [_jsxs("header", { className: "docs-react-demo-header docs-demo-single-head", children: [_jsxs("span", { className: "docs-demo-heading", children: [_jsx("span", { id: `${baseId}-title`, className: "docs-demo-title", children: title }), description ? _jsx("span", { className: "docs-demo-desc", children: _jsx(InlineMarkdown, { text: description }) }) : null] }), _jsx("span", { className: "docs-demo-spacer" }), _jsx(StatusBadge, { status: status }), _jsx(VariantSwitch, { variants: variants, value: variant, onChange: setVariant, title: title, width: variantsWidth }), runnable ? _jsx(FullscreenButton, { onOpen: () => setFullscreen(true), title: title }) : null] }), runnable ? (_jsx("div", { className: "docs-react-demo-preview docs-demo-single-preview", 
+                            // A hint, not a cap: in-page components may grow past it (no height: size to content;
+                            // hosts may set a floor with --docs-demo-preview-min-height). An iframe needs a real height.
+                            style: preview.kind === "runtime"
+                                ? { height: cssLength(heightValue, "360px") }
+                                : heightValue === undefined || heightValue === ""
+                                    ? undefined
+                                    : { minHeight: cssLength(heightValue, "0px") }, children: near ? _jsx(DemoCanvas, { src: src, preview: preview, variant: variant, bleed: bleed, look: look }) : _jsx(Spinner, {}) })) : (_jsx(DemoCanvas, { src: src, preview: preview, variant: variant })), file ? (_jsx(CollapsibleCode, { code: file.content.replace(/\n+$/, ""), language: file.language ?? languageForPath(file.path) ?? null, copyLabel: `Copy ${file.path}`, ...(runnable ? {} : { collapsedLines: 12 }) })) : null] }), dialog] }));
+    }
+    return (_jsx(MultiFileViewer, { rootRef: ref, className: wrapper(layout ?? "pending"), baseId: baseId, mode: mode, src: src, title: title, description: description, variants: variants, variant: variant, onVariant: setVariant, files: files, preview: preview, near: near, height: cssLength(heightValue, "480px"), viewport: props.viewport, bleed: bleed, look: look, status: status, variantsWidth: variantsWidth, href: href, onFullscreen: () => setFullscreen(true), copyDemo: fileList?.length ? copyDemo : undefined, dialog: dialog }));
+}
+function MultiFileViewer({ rootRef, className, baseId, mode, src, title, description, variants, variant, onVariant, files, preview, near, height, viewport, bleed, look, status, variantsWidth, href, onFullscreen, copyDemo, dialog }) {
+    const runnable = preview.kind !== "unavailable";
+    // Nothing to preview without a runtime: open on the code rather than an empty frame.
+    const [tab, setTab] = useState(runnable ? "preview" : "code");
+    const [width, setWidth] = useState(() => VIEWPORTS.find((v) => v.id === viewport)?.width ?? null);
+    const [codeSeen, setCodeSeen] = useState(false);
+    useEffect(() => {
+        if (tab === "code")
+            setCodeSeen(true);
+    }, [tab]);
+    const activeViewport = width === null ? "desktop" : VIEWPORTS.find((v) => v.width === width)?.id;
+    return (_jsxs("section", { ref: rootRef, className: className, "data-docstream-demo": "", "data-demo-src": src, "data-demo-mode": mode, "aria-labelledby": `${baseId}-title`, children: [_jsxs("div", { className: "docs-demo-head", children: [_jsxs("div", { className: "docs-demo-heading", children: [_jsx("div", { id: `${baseId}-title`, className: "docs-demo-title", children: title }), description ? _jsx("p", { className: "docs-demo-desc", children: _jsx(InlineMarkdown, { text: description }) }) : null] }), _jsxs("div", { className: "docs-demo-tools", children: [_jsx(PillTabs, { options: [{ id: "preview", label: "Preview" }, { id: "code", label: "Code" }], value: tab, onChange: setTab, label: `${title} view`, tabId: (id) => `${baseId}-tab-${id}`, panelId: (id) => `${baseId}-panel-${id}` }), _jsx(StatusBadge, { status: status }), _jsx(VariantSwitch, { variants: variants, value: variant, onChange: onVariant, title: title, width: variantsWidth }), tab === "preview" && runnable ? (_jsx("div", { className: "docs-demo-viewports", role: "group", "aria-label": "Preview width", children: VIEWPORTS.map(({ id, label, width: w, Icon }) => (_jsx("button", { type: "button", className: "docs-demo-vp", "aria-pressed": activeViewport === id, "aria-label": w ? `${label} (${w}px)` : label, title: w ? `${label} · ${w}px` : label, onClick: () => setWidth(w), children: _jsx(Icon, { width: 15, height: 15, "aria-hidden": "true" }) }, id))) })) : null, copyDemo ? _jsx(CopyButton, { text: copyDemo, label: "Copy demo as Markdown", className: "docs-demo-icon-btn" }) : null, runnable ? _jsx(FullscreenButton, { onOpen: onFullscreen, title: title }) : null, _jsx(NewTabLink, { href: href, title: title })] })] }), _jsxs("div", { className: "docs-demo-body", children: [_jsx("div", { id: `${baseId}-panel-preview`, role: "tabpanel", "aria-labelledby": `${baseId}-tab-preview`, hidden: tab !== "preview", children: runnable ? (_jsx(PreviewStage, { width: width, onResize: setWidth, height: height, children: near ? _jsx(DemoCanvas, { src: src, preview: preview, variant: variant, bleed: bleed, look: look }) : _jsx(Spinner, {}) })) : (_jsx(DemoCanvas, { src: src, preview: preview, variant: variant })) }), _jsxs("div", { id: `${baseId}-panel-code`, role: "tabpanel", "aria-labelledby": `${baseId}-tab-code`, hidden: tab !== "code", children: [!runnable && tab === "code" ? _jsx(DemoCanvas, { src: src, preview: preview, variant: variant }) : null, codeSeen || tab === "code" ? (files.status === "ready" ? (_jsx(CodeView, { src: src, files: files.value, height: height, id: baseId })) : files.status === "error" ? (_jsx(DemoError, { message: `${src}: ${files.error.message}` })) : (_jsx("div", { className: "docs-demo-code", style: { height }, children: _jsx(Spinner, { label: "Loading files" }) }))) : null] })] }), dialog] }));
+}
+/** Renders a parsed `{% demo %}` block with the resolver and runtime from context. */
+export function DemoBlock({ node }) {
+    return (_jsx(DemoViewer, { src: node.src, title: node.title, description: node.description, height: node.height, layout: node.layout, variants: node.variants, viewport: node.viewport, files: node.files, entry: node.entry, streaming: node.open, status: node.status, bleed: node.bleed, canvasClassName: node.className, surface: node.surface, variantsWidth: node.variantsWidth }));
+}
+/** One demo filling the viewport, for a `?demo=<src>` deep link the host routes. */
+export function DemoFullscreen({ src, resolver: override, variant, className, style }) {
+    const resolver = useDemoResolver(override);
+    const meta = useMeta(resolver, src);
+    const component = useComponent(resolver, src, true);
+    const metaValue = meta.status === "ready" ? meta.value : undefined;
+    const chosen = variant ?? metaValue?.variants?.[0]?.id;
+    if (!resolver)
+        return _jsx(DemoError, { message: `No demo resolver for ${src}` });
+    return (_jsx("div", { className: className ? `docs-demo-fullscreen ${className}` : "docs-demo-fullscreen", style: style, "data-demo-src": src, children: _jsx(DemoCanvas, { src: src, preview: { kind: "component", component }, variant: chosen, bleed: metaValue?.bleed, look: metaValue }) }));
+}
+//# sourceMappingURL=DemoViewer.js.map